//
//  DualMediationSDKPublic.h
//  DualMediationSDK
//
//  对外公开接口 - 简洁版
//

#import <Foundation/Foundation.h>
#if TARGET_OS_IPHONE
#import <UIKit/UIKit.h>
#else
#import <Cocoa/Cocoa.h>
#endif
#import "DMLifecycleTypes.h"

@class UIViewController;
@class UIView;
typedef NS_ENUM(NSUInteger,DMBannerScene);

typedef NS_ENUM(NSUInteger, DMInterstitialScene);
typedef NS_ENUM(NSUInteger, DMLogLevel);
typedef NS_ENUM(NSUInteger, DMNativePosition);
@protocol DMAdDelegate;          // ← 协议前向声明
typedef NS_ENUM(NSUInteger, DMBannerScene);      // 前向声明
typedef NS_ENUM(NSUInteger, DMBannerPosition);
typedef NS_ENUM(NSUInteger, BannerPosition);     // ★ 新增前向声明
typedef NS_ENUM(NSUInteger, DMInterstitialScene); //向前说明
typedef NS_ENUM(NSUInteger, DMNativePosition); //向前说明

NS_ASSUME_NONNULL_BEGIN

/**
 * 免广告类型枚举
 * 用于设置和查询不同类型广告的免广告状态
 */
typedef NS_ENUM(NSInteger, DMAdBanType) {
    DMAdBanTypeReward = 0,      // 激励视频
    DMAdBanTypeInsert = 1,      // 插屏广告
    DMAdBanTypeBanner = 2,      // BANNER广告
    DMAdBanTypeSplash = 3,      // 开屏广告
    DMAdBanTypeNative = 4,      // 原生广告
    DMAdBanTypeAudio = 5,       // 音频广告
    DMAdBanTypeAll = 6,         // 所有广告
    DMAdBanTypeUnknown = -1     // UNKNOWN
};

/**
 * DualMediationSDK 对外公开接口
 * 
 * 提供最简洁的SDK集成方式，只需几行代码即可完成SDK初始化和广告展示
 */
@interface DualMediationSDKPublic : NSObject

#pragma mark - 单例访问

/**
 * 获取SDK单例实例
 */
+ (DualMediationSDKPublic *)sharedInstance;

#pragma mark - 核心接口

/**
 * 快速初始化SDK
 * 
 * @param completion 初始化完成回调
 */
- (void)initializeSDKWithCompletion:(void(^)(BOOL success, NSError * _Nullable error))completion;

#pragma mark - 状态查询

/**
 * 检查SDK是否已初始化
 */
@property (nonatomic, readonly) BOOL isSDKInitialized;

/**
 * 检查合规是否已完成
 */
@property (nonatomic, readonly) BOOL isComplianceCompleted;

/**
 * 获取SDK版本信息
 */
@property (nonatomic, readonly) NSString *sdkVersion;

#pragma mark - 调试功能

/**
 * 启用调试模式（仅在开发阶段使用）
 * @param enabled 是否启用调试模式
 */
- (void)setDebugModeEnabled:(BOOL)enabled;

/**
 * 获取当前调试模式状态
 */
@property (nonatomic, readonly) BOOL isDebugModeEnabled;

#pragma mark - 简洁的广告显示接口

// MARK: - 激励视频广告

/**
 * 展示激励视频广告
 * @param placementId 广告位ID
 * @param viewController 展示的视图控制器
 */
- (void)showRewardedVideo:(NSString *)placementId viewController:(UIViewController *)viewController;

/**
 * 检查激励视频是否准备就绪
 * @param placementId 广告位ID
 * @return 是否准备就绪
 */
- (BOOL)isRewardedVideoReady:(NSString *)placementId;

/**
 * 显示指定场景的激励视频广告
 * @param scene 场景标识符，用于区分不同的广告展示场景
 */
+ (void)showRewardedVideoForScene:(NSString *)scene;

/**
 * 检查指定场景的激励视频广告是否准备就绪
 * @param scene 场景标识符
 * @return YES表示广告已准备就绪，NO表示广告未准备就绪
 */
+ (BOOL)isRewardedVideoReadyForScene:(NSString *)scene;

// MARK: - 插屏广告

/**
 * 展示插屏广告
 * @param placementId 广告位ID
 * @param viewController 展示的视图控制器
 */
- (void)showInterstitial:(NSString *)placementId viewController:(UIViewController *)viewController;

/**
 * 检查插屏广告是否准备就绪
 * @param placementId 广告位ID
 * @return 是否准备就绪
 */
- (BOOL)isInterstitialReady:(NSString *)placementId;

// MARK: - 开屏广告

/**
 * 展示开屏广告
 * @param placementId 广告位ID
 * @param viewController 展示的视图控制器
 */
- (void)showSplash:(NSString *)placementId viewController:(UIViewController *)viewController;

/**
 * 检查开屏广告是否准备就绪
 * @param placementId 广告位ID
 * @return 是否准备就绪
 */
- (BOOL)isSplashReady:(NSString *)placementId;

/**
 * 设置开屏广告禁用状态
 * @param isDisable 是否禁用开屏广告
 */
- (void)setSplashAdDisable:(BOOL)isDisable;

// MARK: - Banner广告

/**
 * 展示Banner广告
 * @param placementId 广告位ID
 * @param containerView 容器视图
 * @param position 位置（可选，nil表示使用默认位置）
 */
- (void)showBanner:(NSString *)placementId 
     containerView:(UIView *)containerView 
          position:(nullable NSValue *)position;

/**
 * 检查Banner广告是否准备就绪
 * @param placementId 广告位ID
 * @return 是否准备就绪
 */
- (BOOL)isBannerReady:(NSString *)placementId;

/**
 * 隐藏Banner广告
 * @param placementId 广告位ID
 */
- (void)hideBanner:(NSString *)placementId;

// MARK: - 原生广告

/**
 * 展示原生广告
 * @param placementId 广告位ID
 * @param containerView 容器视图
 * @param adView 广告视图（可选，nil表示使用默认视图）
 */
- (void)showNativeAd:(NSString *)placementId 
        containerView:(UIView *)containerView 
               adView:(nullable UIView *)adView;

/**
 * 检查原生广告是否准备就绪
 * @param placementId 广告位ID
 * @return 是否准备就绪
 */
- (BOOL)isNativeAdReady:(NSString *)placementId;

/**
 * 获取原生广告数据
 * @param placementId 广告位ID
 * @return 原生广告数据字典
 */
- (nullable NSDictionary *)getNativeAdData:(NSString *)placementId;

#pragma mark - 原生广告场景化接口

/**
 * 展示原生广告（场景化接口）
 * @param sceneValue 场景值，用于场景埋点使用，建议用英文命名
 * @param position 原生广告位置（顶部/底部）
 */
- (void)showNative:(NSString *)sceneValue position:(DMNativePosition)position;

/**
 * 隐藏原生广告（场景化接口）
 * @param sceneValue 场景值，用于场景埋点使用，建议用英文命名
 */
- (void)hideNative:(NSString *)sceneValue;

// 创建原生广告容器视图
- (UIView *)createNativeContainerViewForPosition:(DMNativePosition)position;

// 执行原生广告显示的具体逻辑
- (void)performNativeAdShowWithScene:(NSString *)sceneValue position:(DMNativePosition)position;

#pragma mark - 登录接口

/**
 * 用户登录接口
 * @param appId 应用ID
 * @param iosUuid iOS设备唯一标识
 * @param countryCode 地区代码（可选）
 * @param completion 登录完成回调 (success, userInfo, error)
 */
- (void)loginWithAppId:(NSString *)appId
              iosUuid:(NSString *)iosUuid
          countryCode:(NSString * _Nullable)countryCode
           completion:(void(^)(BOOL success, NSDictionary * _Nullable userInfo, NSError * _Nullable error))completion;

#pragma mark - 广告策略接口

/**
 * 获取广告策略接口
 * @param appId 应用ID
 * @param uuid 用户唯一ID（可选，如果为空则自动使用登录后保存的UUID）
 * @param completion 获取完成回调 (success, response, error)
 */
- (void)getAdStrategyWithAppId:(NSString *)appId
                          uuid:(NSString * _Nullable)uuid
                    completion:(void(^)(BOOL success, id _Nullable response, NSError * _Nullable error))completion;

#pragma mark - 产品策略接口

/**
 * 获取产品策略接口
 * @param appId 应用ID
 * @param uuid 用户唯一ID（可选，如果为空则自动使用登录后保存的UUID）
 * @param completion 获取完成回调 (success, strategyData, error)
 */
- (void)getGameStrategyWithAppId:(NSString *)appId
                            uuid:(NSString * _Nullable)uuid
                      completion:(void(^)(BOOL success, NSArray * _Nullable strategyData, NSError * _Nullable error))completion;

#pragma mark - FCM设备令牌上传

/**
 * 上传FCM设备令牌
 * @param appId 应用ID
 * @param uuid 设备UUID（可选，如果为空则自动使用登录后保存的UUID）
 * @param fcmToken FCM设备令牌
 * @param completion 完成回调
 */
- (void)uploadFCMTokenWithAppId:(NSString *)appId
                           uuid:(NSString * _Nullable)uuid
                       fcmToken:(NSString *)fcmToken
                     completion:(void(^)(BOOL success, NSString * _Nullable message, NSError * _Nullable error))completion;

#pragma mark - 设备信息接口

/**
 * 获取设备基本信息
 * @return 设备信息字典
 */
- (NSDictionary *)getDeviceInfo;

/**
 * 获取设备详细信息
 * @return 设备详细信息字典
 */
- (NSDictionary *)getDetailedDeviceInfo;

/**
 * 获取设备网络信息
 * @return 网络信息字典
 */
- (NSDictionary *)getNetworkInfo;

#pragma mark - FCM推送接口

/**
 * 处理远程通知
 * @param userInfo 通知信息
 * @param completionHandler 完成回调
 */
- (void)handleRemoteNotification:(NSDictionary *)userInfo 
                completionHandler:(nullable void (^)(NSInteger))completionHandler;

/**
 * 处理通知点击事件
 * @param userInfo 通知信息
 * @param viewController 当前视图控制器
 */
- (void)handleNotificationTap:(NSDictionary *)userInfo 
               viewController:(UIViewController *)viewController;

/**
 * 检查是否为FCM推送通知
 * @param userInfo 通知信息
 * @return 是否为FCM通知
 */
- (BOOL)isFCMNotification:(NSDictionary *)userInfo;

#pragma mark - 震动功能接口

/**
 * 执行简单震动
 * @param duration 震动时长（毫秒）
 */
- (void)vibrateWithDuration:(NSTimeInterval)duration;

/**
 * 执行模式震动
 * @param pattern 震动模式数组（震动时长和间隔时长交替）
 */
- (void)vibrateWithPattern:(NSArray<NSNumber *> *)pattern;

/**
 * 执行类型震动
 * @param type 震动类型（0-轻微，1-中等，2-强烈，3-选择，4-成功，5-警告，6-错误）
 */
- (void)vibrateWithType:(NSInteger)type;

/**
 * 执行高级震动配置
 * @param config 震动配置字典
 * @param progressCallback 进度回调（可选）
 * @return 震动ID
 */
- (NSString *)vibrateWithConfig:(NSDictionary *)config 
                progressCallback:(nullable void (^)(NSString *vibrateId, float progress))progressCallback;

/**
 * 取消震动
 * @param vibrateId 震动ID
 */
- (void)cancelVibrate:(NSString *)vibrateId;

/**
 * 暂停震动
 * @param vibrateId 震动ID
 */
- (void)pauseVibrate:(NSString *)vibrateId;

/**
 * 恢复震动
 * @param vibrateId 震动ID
 */
- (void)resumeVibrate:(NSString *)vibrateId;

/**
 * 检查设备是否支持震动
 * @return 是否支持震动
 */
- (BOOL)isVibrateSupported;

/**
 * 检查设备是否支持触觉反馈
 * @return 是否支持触觉反馈
 */
- (BOOL)isHapticFeedbackSupported;

/**
 * 获取当前活跃震动数量
 * @return 活跃震动数量
 */
- (NSInteger)getActiveVibrateCount;

#pragma mark - SDK启动配置接口

/**
 * 手动应用SDK启动配置
 * 从广告策略中获取并应用SDK启动配置参数
 * 注意：SDK会在初始化完成后自动应用配置，通常不需要手动调用
 */
- (void)applySDKStartupConfiguration;

/**
 * 应用默认SDK启动配置
 * 当无法获取线上配置时，使用本地默认配置
 */
- (void)applyDefaultSDKStartupConfiguration;

#pragma mark - 便捷方法

/**
 * 快速启动SDK
 */
+ (void)IninSDK;

/**
 * 快速启动SDK（带回调）
 * @param completion 初始化完成回调，success表示是否成功，error表示失败原因
 */
+ (void)IninSDKWithCompletion:(void(^)(BOOL success, NSError * _Nullable error))completion;

/**
 * 启用调试模式
 */
+ (void)enableDebugMode;

#pragma mark - 日志功能接口

// DMLogLevel枚举已在DMAdConfig.h中定义

/**
 * 设置日志级别
 * @param level 日志级别
 */
- (void)setLogLevel:(DMLogLevel)level;

/**
 * 启用或禁用日志
 * @param enabled 是否启用
 */
- (void)setLogEnabled:(BOOL)enabled;

/**
 * 记录信息日志
 * @param message 日志消息
 */
- (void)logInfo:(NSString *)message;

/**
 * 记录警告日志
 * @param message 日志消息
 */
- (void)logWarning:(NSString *)message;

/**
 * 记录错误日志
 * @param message 日志消息
 */
- (void)logError:(NSString *)message;

/**
 * 启用实时日志弹窗（仅调试环境）
 */
- (void)enableRealtimeLogPopup;

/**
 * 获取日志文件路径
 * @return 日志文件路径数组
 */
- (NSArray<NSString *> *)getLogFilePaths;

#pragma mark - UUID管理接口

/**
 * 获取或创建登录UUID
 * @return 登录用的UUID字符串
 */
- (NSString *)getOrCreateLoginUUID;

/**
 * 清除登录UUID
 */
- (void)clearLoginUUID;

/**
 * 检查是否存在登录UUID
 * @return YES表示存在，NO表示不存在
 */
- (BOOL)hasLoginUUID;

#pragma mark - 插屏广告场景接口

// DMInterstitialScene枚举已在DMInterstitialScenes.h中定义

/**
 * 展示场景化插屏广告（推荐使用，基于showInterAd优化）
 * @param sceneName 插屏场景名称（如：@"SCENE_INTER_LEVEL_WIN"）
 * 注意：所有策略参数（关卡间隔、每日限制等）由后端广告策略控制，不可外部修改
 */
- (void)showInterstitialForScene:(NSString *)sceneName;

/**
 * 检查场景化插屏广告是否可用
 * @param sceneName 插屏场景名称
 * @return 是否可用
 */
- (BOOL)isInterstitialReadyForScene:(NSString *)sceneName;

/**
 * 展示场景插屏广告（保留原有接口，向后兼容）
 * @param adScene 广告场景字符串
 */
- (void)showInterAd:(NSString *)adScene;

/**
 * 展示场景化插屏广告（使用枚举）
 * @param scene 广告场景枚举
 * @param viewController 展示的视图控制器
 * @param currentLevel 当前关卡（可选）
 * @param delegate 广告代理（可选）
 */
- (void)showInterstitialForSceneEnum:(DMInterstitialScene)scene
                      viewController:(UIViewController *)viewController
                        currentLevel:(NSInteger)currentLevel
                            delegate:(nullable id)delegate;

/**
 * 预加载场景插屏广告
 * @param scene 广告场景
 */
- (void)preloadInterstitialForScene:(DMInterstitialScene)scene;

#pragma mark - 广告代理管理

/**
 * 设置广告代理
 * @param delegate 广告代理对象
 */
- (void)setAdDelegate:(nullable id<DMAdDelegate>)delegate;

/**
 * 获取当前广告代理
 * @return 当前广告代理对象
 */
- (nullable id<DMAdDelegate>)adDelegate;

#pragma mark - Banner广告重构接口

// Banner广告相关枚举已在DMBannerTypes.h中定义

/**
 * 展示场景化Banner广告（推荐使用，基于后端策略）
 * @param sceneName Banner场景名称（如：@"SCENE_BANNER_INIT"）
 * 注意：所有策略参数（位置、每日限制、短屏检测等）由后端广告策略控制
 */
- (void)showBannerForScene:(NSString *)sceneName;

/**
 * 隐藏场景化Banner广告
 * @param sceneName Banner场景名称
 */
- (void)hideBannerForScene:(NSString *)sceneName;

/**
 * 检查场景化Banner广告是否可用
 * @param sceneName Banner场景名称
 * @return 是否可用
 */
- (BOOL)isBannerReadyForScene:(NSString *)sceneName;



/**
 * 展示场景化Banner广告（使用枚举，兼容原有接口）
 * @param scene Banner场景
 * @param position Banner位置
 * @param enableShortScreenDetection 是否启用短屏检测
 * @param delegate 广告代理（可选）
 */
- (void)showBannerForSceneEnum:(DMBannerScene)scene
                      position:(DMBannerPosition)position
        enableShortScreenDetection:(BOOL)enableShortScreenDetection
                          delegate:(nullable id<DMAdDelegate>)delegate;

/**
 * 预加载场景Banner广告
 * @param scene Banner场景
 */
- (void)preloadBannerForScene:(DMBannerScene)scene;

/**
 * 销毁Banner广告
 * @param sceneName Banner场景名称
 */
- (void)destroyBannerForScene:(NSString *)sceneName;

/**
 * 展示Banner广告（新增接口，参考Android SDK设计）
 * @param sceneValue 场景值，用于场景埋点使用，建议用英文命名
 * @param position Banner位置（Bottom/Top/BottomTop）
 * @param enableShortScreenDetection 是否开启短屏Banner不展示检测
 */
- (void)showBannerAd:(NSString *)sceneValue 
            position:(BannerPosition)position 
enableShortScreenDetection:(BOOL)enableShortScreenDetection;

#pragma mark - Facebook功能接口

/**
 * 初始化Facebook SDK
 * @param appId Facebook应用ID
 * @param delegate 回调代理
 */
- (void)initializeFacebook:(NSString *)appId delegate:(nullable id<DMAdDelegate>)delegate;

/**
 * 处理Facebook URL回调
 * @param url 回调URL
 * @return 是否处理成功
 */
- (BOOL)handleFacebookURL:(NSURL *)url;

/**
 * Facebook登录
 */
- (void)facebookLogin;

/**
 * Facebook登出
 */
- (void)facebookLogout;

/**
 * 检查Facebook登录状态
 * @return 是否已登录
 */
- (BOOL)isFacebookLoggedIn;

/**
 * 获取Facebook访问令牌
 * @return 访问令牌字符串，未登录时返回nil
 */
- (nullable NSString *)getFacebookAccessToken;

/**
 * 获取Facebook用户信息
 */
- (void)getFacebookUserInfo;

/**
 * 获取缓存的Facebook用户信息
 * @return 用户信息字典，无缓存时返回nil
 */
- (nullable NSDictionary *)getCachedFacebookUserInfo;

/**
 * Facebook分享链接
 * @param url 要分享的链接
 * @param quote 分享引用文本（可选）
 */
- (void)facebookShareLink:(NSString *)url quote:(nullable NSString *)quote;

/**
 * Facebook分享图片
 * @param image 要分享的图片
 */
- (void)facebookShareImage:(UIImage *)image;

/**
 * 启用Facebook详细日志
 * @param enabled 是否启用
 */
- (void)setFacebookVerboseLoggingEnabled:(BOOL)enabled;

/**
 * 获取Facebook SDK版本
 * @return SDK版本字符串
 */
//- (NSString *)getFacebookSDKVersion;

#pragma mark - 免广告设置接口

/**
 * 设置免广告状态
 * @param adBanType 免广告类型，指定要设置的广告类型
 * @param isRemove 是否免广告，YES表示免广告，NO表示不免广告
 */
- (void)setRemoveAd:(DMAdBanType)adBanType isRemove:(BOOL)isRemove;

/**
 * 获取免广告状态
 * @param adBanType 要查询的广告类型
 * @return YES表示该类型广告已设置免广告，NO表示未设置免广告
 */
- (BOOL)isRemoveAd:(DMAdBanType)adBanType;

#pragma mark - 内购功能接口

/**
 * 核销内购订单
 * @param originalTransactionId 原始交易ID
 * @param successCallback 成功回调
 * @param failureCallback 失败回调
 */
- (void)acknowledgeInAppPurchaseWithOriginalTransactionId:(NSString *)originalTransactionId
                                          successCallback:(DMInAppPurchaseSuccessCallback)successCallback
                                          failureCallback:(DMInAppPurchaseFailureCallback)failureCallback;

/**
 * 获取未核销订单列表
 * @param successCallback 成功回调，返回未核销订单数组
 * @param failureCallback 失败回调
 */
- (void)fetchUnacknowledgedOrdersWithSuccessCallback:(DMUnacknowledgedOrdersCallback)successCallback
                                      failureCallback:(DMInAppPurchaseFailureCallback)failureCallback;

/**
 * 校验内购收据
 * @param appId 应用ID
 * @param receiptData 收据数据
 * @param successCallback 成功回调
 * @param failureCallback 失败回调
 */
- (void)verifyInAppReceiptWithAppId:(NSString *)appId
                        receiptData:(NSData *)receiptData
                    successCallback:(DMInAppPurchaseSuccessCallback)successCallback
                    failureCallback:(DMInAppPurchaseFailureCallback)failureCallback;

/**
 * 开始内购（消耗性/非消耗性商品购买）
 * @param productId 商品ID
 */
- (void)launchInAppPurchase:(NSString *)productId;

/**
 * 恢复内购
 * @param productId 商品ID
 */
- (void)restoreInAppPurchase:(NSString *)productId;

/**
 * 获取商品列表
 * @param productIds 商品ID数组
 */
- (void)requestProductsList;

#pragma mark ---- adjust 事件上报 ---------

/**
 * 上报Adjust事件（同步方式）
 * @param eventId 事件ID
 */
- (void)trackAdjustEvent:(NSString *)eventId;

#pragma mark - 数数 SDK 事件上报接口

/**
 * 设置数数SDK公共属性（会追加到后续所有事件）
 * @param jsonStr 公共属性，支持NSDictionary或JSON字符串
 */
- (void)thinkingSetSuperPropertiesJsonStr:(id)jsonStr;

/**
 * 上报数数SDK普通事件
 * @param key 事件名
 * @param jsonStr 事件属性，支持NSDictionary或JSON字符串
 */
- (void)thinkingTrackEventWithKey:(NSString *)key jsonStr:(id)jsonStr;

/**
 * 设置数数SDK用户属性（可覆盖）
 * @param jsonStr 用户属性，支持NSDictionary或JSON字符串
 */
- (void)thinkingTrackUserPropertiesJsonStr:(id)jsonStr;

/**
 * 设置数数SDK用户属性（仅首次设置生效）
 * @param key 属性名
 * @param value 属性值
 */
- (void)thinkingUser_setOnceWithKey:(NSString *)key value:(NSString *)value;

#pragma mark - 关卡事件埋点接口

/**
 * @brief 追踪关卡开始事件
 *
 * 当玩家开始某个关卡时调用此方法进行埋点追踪。
 * 该事件用于统计关卡的开始情况和玩家的游戏进度。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家开始第5关
 * [DualMediationSDKPublic SDK_Level_Start:5];
 * ```
 */
+ (void)SDK_Level_Start:(NSInteger)level;

/**
 * @brief 追踪关卡胜利事件
 *
 * 当玩家成功完成某个关卡时调用此方法进行埋点追踪。
 * 该事件用于统计关卡的通过率和玩家的游戏成就。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家通过第5关
 * [DualMediationSDKPublic SDK_Level_Win:5];
 * ```
 */
+ (void)SDK_Level_Win:(NSInteger)level;

/**
 * @brief 追踪关卡失败事件
 *
 * 当玩家在某个关卡中失败时调用此方法进行埋点追踪。
 * 该事件用于统计关卡的难度和玩家的挑战情况。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家在第5关失败
 * [DualMediationSDKPublic SDK_Level_Lose:5];
 * ```
 */
+ (void)SDK_Level_Lose:(NSInteger)level;

/**
 * @brief 追踪关卡进入事件
 *
 * 当玩家进入某个关卡界面时调用此方法进行埋点追踪。
 * 该事件用于统计关卡的访问情况和玩家的浏览行为。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家进入第5关界面
 * [DualMediationSDKPublic SDK_Level_Enter:5];
 * ```
 */
+ (void)SDK_Level_Enter:(NSInteger)level;

/**
 * @brief 追踪关卡复活事件
 *
 * 当玩家在关卡中使用复活功能时调用此方法进行埋点追踪。
 * 该事件用于统计复活功能的使用情况和玩家的付费行为。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家在第5关使用复活
 * [DualMediationSDKPublic SDK_Level_Revive:5];
 * ```
 */
+ (void)SDK_Level_Revive:(NSInteger)level;

/**
 * @brief 追踪关卡重试事件
 *
 * 当玩家选择重新开始某个关卡时调用此方法进行埋点追踪。
 * 该事件用于统计关卡的重试情况和玩家的坚持程度。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家重试第5关
 * [DualMediationSDKPublic SDK_Level_Retry:5];
 * ```
 */
+ (void)SDK_Level_Retry:(NSInteger)level;

/**
 * @brief 追踪关卡道具使用事件
 *
 * 当玩家在关卡中使用道具时调用此方法进行埋点追踪。
 * 该事件用于统计道具的使用情况和玩家的策略选择。
 *
 * @param level 关卡等级，建议从1开始的正整数
 *
 * @note 此方法会异步执行，不会阻塞当前线程
 * @note 实际追踪的关卡值会加上偏移量以确保数据的一致性
 *
 * @example
 * ```objc
 * // 玩家在第5关使用道具
 * [DualMediationSDKPublic SDK_Level_Prop:5];
 * ```
 */
+ (void)SDK_Level_Prop:(NSInteger)level;

#pragma mark - 测试接口

/**
 * @brief 运行关卡事件埋点测试
 *
 * 该方法用于测试和验证关卡事件埋点功能是否正常工作。
 * 包括测试关卡事件追踪、配置控制、事件上报开关和异常情况处理。
 *
 * @note 此方法仅用于开发和测试阶段，生产环境中请谨慎使用
 * @note 测试过程中会输出详细的日志信息，便于调试和验证
 *
 * @example
 * ```objc
 * // 运行关卡事件埋点测试
 * [DualMediationSDKPublic runLevelEventTrackingTests];
 * ```
 */
+ (void)runLevelEventTrackingTests;


#pragma mark - iOS标准生命周期方法

/**
 * 应用启动完成
 * @param application UIApplication实例
 * @param launchOptions 启动选项字典
 * @return 是否成功处理启动
 */
- (BOOL)applicationDidFinishLaunching:(UIApplication *)application withOptions:(nullable NSDictionary *)launchOptions;

/**
 * 应用变为活跃状态
 * @param application UIApplication实例
 */
- (void)applicationDidBecomeActive:(UIApplication *)application;

/**
 * 应用将要失去活跃状态
 * @param application UIApplication实例
 */
- (void)applicationWillResignActive:(UIApplication *)application;

/**
 * 应用进入后台
 * @param application UIApplication实例
 */
- (void)applicationDidEnterBackground:(UIApplication *)application;

/**
 * 应用将要进入前台
 * @param application UIApplication实例
 */
- (void)applicationWillEnterForeground:(UIApplication *)application;

/**
 * 应用将要终止
 * @param application UIApplication实例
 */
- (void)applicationWillTerminate:(UIApplication *)application;

/**
 * 应用收到内存警告
 * @param application UIApplication实例
 */
- (void)applicationDidReceiveMemoryWarning:(UIApplication *)application;

/**
 * 应用收到远程推送通知
 * @param application UIApplication实例
 * @param userInfo 推送通知信息
 */
- (void)applicationDidReceiveRemoteNotification:(UIApplication *)application userInfo:(NSDictionary *)userInfo;

/**
 * 应用收到本地通知
 * @param application UIApplication实例
 * @param notification 本地通知对象
 */
- (void)applicationDidReceiveLocalNotification:(UIApplication *)application notification:(UILocalNotification *)notification;

/**
 * 应用打开URL
 * @param application UIApplication实例
 * @param url 要打开的URL
 * @param options 打开选项
 * @return 是否成功处理URL
 */
- (BOOL)applicationOpenURL:(UIApplication *)application url:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options;

/**
 * 应用继续用户活动
 * @param application UIApplication实例
 * @param userActivity 用户活动对象
 * @param restorationHandler 恢复处理器
 * @return 是否成功处理用户活动
 */
- (BOOL)applicationContinueUserActivity:(UIApplication *)application userActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * _Nullable restorableObjects))restorationHandler;

#pragma mark - Firebase Analytics接口

/**
 * 记录Firebase Analytics事件
 * @param eventName 事件名称
 * @param parameters 事件参数（可选）
 */
- (void)logFirebaseEvent:(NSString *)eventName parameters:(nullable NSDictionary<NSString *, id> *)parameters;

/**
 * 记录Firebase Analytics事件（带完成回调）
 * @param eventName 事件名称
 * @param parameters 事件参数（可选）
 * @param completion 完成回调
 */
- (void)logFirebaseEvent:(NSString *)eventName 
              parameters:(nullable NSDictionary<NSString *, id> *)parameters 
              completion:(nullable void(^)(NSError * _Nullable error))completion;

/**
 * 设置Firebase Analytics用户属性
 * @param value 属性值
 * @param name 属性名称
 */
- (void)setFirebaseUserProperty:(nullable NSString *)value forName:(NSString *)name;

/**
 * 设置Firebase Analytics用户ID
 * @param userId 用户ID
 */
- (void)setFirebaseUserId:(nullable NSString *)userId;

#pragma mark - 实时日志窗口接口

/**
 * 显示实时日志窗口
 * 在当前窗口上显示实时日志监控界面
 */
- (void)showRealTimeLogWindow;

/**
 * 隐藏实时日志窗口
 * 隐藏当前显示的实时日志监控界面
 */
- (void)hideRealTimeLogWindow;

/**
 * 检查实时日志窗口是否正在显示
 * @return YES表示正在显示，NO表示已隐藏
 */
- (BOOL)isRealTimeLogWindowVisible;

/**
 * 启用或禁用IMLogUtils实时监听
 * @param enable YES启用监听，NO禁用监听
 */
- (void)enableRealTimeLogMonitoring:(BOOL)enable;

/**
 * 设置实时日志的最小显示级别
 * @param minLevel 最小日志级别
 */
- (void)setRealTimeLogMinimumLevel:(NSInteger)minLevel;

/**
 * 设置实时日志的可见标签过滤
 * @param tags 要显示的标签数组，传nil表示显示所有标签
 */
- (void)setRealTimeLogVisibleTags:(nullable NSArray<NSNumber *> *)tags;

/**
 * 清除实时日志窗口中的所有日志内容
 */
- (void)clearRealTimeLogWindow;

/**
 * 导出实时日志到文件
 * @param includeSystemLogs 是否包含系统日志
 * @param completion 导出完成回调，返回文件路径或错误信息
 */
- (void)exportRealTimeLogsWithSystemLogs:(BOOL)includeSystemLogs 
                              completion:(nullable void(^)(NSString * _Nullable filePath, NSError * _Nullable error))completion;

/**
 * 获取实时日志统计信息
 * @return 包含日志统计信息的字典
 */
- (NSDictionary *)getRealTimeLogStatistics;

/**
 * 设置实时日志格式化选项
 * @param showTimestamp 是否显示时间戳
 * @param showLevel 是否显示日志级别
 * @param showTag 是否显示标签
 * @param showThread 是否显示线程信息
 */
- (void)setRealTimeLogFormat:(BOOL)showTimestamp
                   showLevel:(BOOL)showLevel
                     showTag:(BOOL)showTag
                  showThread:(BOOL)showThread;

/**
 * 在实时日志窗口中搜索日志内容
 * @param keyword 搜索关键词
 * @param caseSensitive 是否大小写敏感
 */
- (void)searchRealTimeLogs:(NSString *)keyword caseSensitive:(BOOL)caseSensitive;

#pragma mark - 实时日志悬浮按钮

/**
 * 显示实时日志悬浮按钮
 * 在屏幕右侧显示一个可拖拽的小按钮，点击可打开/关闭实时日志窗口
 */
- (void)showFloatingLogButton;

/**
 * 隐藏实时日志悬浮按钮
 */
- (void)hideFloatingLogButton;

/**
 * 悬浮按钮是否显示中
 */
- (BOOL)isFloatingLogButtonVisible;

#pragma mark - 应用信息界面接口

/**
 * 显示应用信息界面
 * 在当前窗口上显示应用信息监控界面
 * @param viewController 用于展示的视图控制器
 */
- (void)showAppInfoViewController:(UIViewController *)viewController;



#pragma mark - 网络状态（对外可用）

/** 网络状态枚举 */
typedef NS_ENUM(NSInteger, DMNetworkStatus) {
    DMNetworkStatusUnknown        = -1,  // 未知
    DMNetworkStatusNotReachable   = 0,   // 无网络
    DMNetworkStatusWWAN           = 1,   // 蜂窝
    DMNetworkStatusWiFi           = 2    // Wi-Fi
};

/** 网络变化通知（可选给外部用 NSNotification 订阅） */
FOUNDATION_EXPORT NSNotificationName const DMNetworkStatusDidChangeNotification;
/** 通知 userInfo 中的新状态 key（NSNumber<DMNetworkStatus>） */
FOUNDATION_EXPORT NSString * const DMNetworkStatusUserInfoKey;

/** 当前网络状态（类属性，便于随取随用） */
@property (class, nonatomic, readonly) DMNetworkStatus currentNetworkStatus;

/**
 开始监听网络状态变化
 @param callback 网络状态变化回调（可为 nil，仅用通知）
 */
+ (void)startNetworkMonitoringWithCallback:(void (^_Nullable)(DMNetworkStatus status))callback;

/** 停止监听网络状态变化 */
+ (void)stopNetworkMonitoring;

@end

NS_ASSUME_NONNULL_END
